Getting Started
The Starter Template
The recommended way to create a new mobile feature or widget is to use the Nx generators provided by @cdx-extensions/widget-template-mobile. The package exposes two generators — feature and widget — each producing a correctly structured React Native library wired for @cdx-extensions/di-sdk (PlatformSDK), built with tsup, and aligned with the CDX mobile patterns used in the reference implementations.
Prerequisites
Before you run either generator, complete the prerequisites and environment setup described in the CDX Extensibility Apps README.
Choose a Generator
| Generator | Use when | Example |
|---|---|---|
feature | You are building a full-screen experience that appears as a new bottom tab in the mobile banking app |  Sample Feature — full-screen bottom tab |
widget | You are building a component embedded only in an existing home screen |  Sample Widget — embedded home screen component |
Commands
Feature — new bottom tab with a full-screen experience:
nx generate @cdx-extensions/widget-template-mobile:feature --fiId=<fi-id> --name=<name>
Widget — embedded component:
nx generate @cdx-extensions/widget-template-mobile:widget --fiId=<fi-id> --name=<name>
| Option | Required | Description |
|---|---|---|
--fiId | Yes | Your FI Id. Used as the package scope — the generated package name is @<fiId>-extensions/<name> |
--name | Yes | Name of the feature or widget (e.g. account-summary). Used as the Nx project name and folder name |
Examples
# Feature
nx generate @cdx-extensions/widget-template-mobile:feature --fiId=0000 --name=my-feature
# Widget
nx generate @cdx-extensions/widget-template-mobile:widget --fiId=0000 --name=my-widget
What Gets Created
Feature (scaffolded under features/mobile/<name>/ by default):
features/mobile/my-feature/
├── src/
│ ├── my-feature.tsx ← feature component — start here
│ ├── index.ts ← named + default exports
│ ├── config.ts ← API base URL (baseUrl) and endpoint path (apiPath)
│ └── types/
│ └── branding.ts ← MobileBrandingTheme types and resolveColors helper
├── package.json
├── project.json
├── tsconfig.json
└── README.md
Widget (scaffolded under widgets/mobile/<name>/ by default):
widgets/mobile/my-widget/
├── src/
│ ├── my-widget.tsx ← widget component — start here
│ ├── index.ts ← named + default exports
│ └── types/
│ └── branding.ts ← MobileBrandingTheme types and resolveColors helper
├── package.json
├── project.json
├── tsconfig.json
└── README.md
The widget starter template is minimal. Add API calls, navigation, or any SDK capability as your project requires — see the investment-portfolio reference implementation for an example that uses getHttpClient().
After You Generate
The generator registers your project in the sandbox automatically. From the repository root:
npm install
npx nx start mobile-sandbox
Press i for the iOS Simulator, a for Android Emulator, or scan the QR code with Expo Go on a physical device. The sandbox provides the mock platform (user context, branding, HTTP client) so your feature or widget can run without the production host app.
What You Can Edit
| File / Folder | Can you edit? | Notes |
|---|---|---|
src/ | Yes, freely | All your UI and business logic goes here |
package.json | Partially | Change name, version, peerDependencies. Keep the build scripts and tsup config as-is |
project.json | Partially | Only change name, outputs, and cwd to match your project folder |
tsconfig*.json | No | Required TypeScript config |
Common Mistakes to Avoid
| Mistake | Why It Breaks |
|---|---|
Using fetch() or Axios directly instead of sdk.getHttpClient() | Bypasses platform auth and security in production |
Importing from @cdx-extensions/di-sdk-mobile in feature or widget code | Only the host app initialises the platform — features and widgets import from @cdx-extensions/di-sdk only |
| Adding peer or runtime dependencies outside the versions listed in the CDX Extensibility Apps README | Version conflicts with the host mobile banking app at runtime |
Forgetting to export from src/index.ts | The sandbox (or host app) cannot import your component |
Changing the tsup build scripts in package.json | Breaks the CJS/ESM dual output required for Metro and production bundling |
Next Steps
Mobile platform guides:
- SDK Reference — SDK packages, methods, and usage
- Platform Capabilities (Local) — How local development works with mock data
- Host App Integration — Repository structure and submission process